The purpose of the NewSTAK XCMD is to provide a quick way to create a new HyperCard stack entirely under script control. No help from a user is required. The newly created stack doesn't have to look like the parent stack that created it. Unlike a stack created via HyperCard's standard "New Stack" command, the new stack may contain several backgrounds. You can even specify any of several different stacks to create, depending on circumstances.
The stack designer (that's you) will need the shareware application called "D2R" by Jason Haines, to create a resource out of the data fork of a stack, as explained below. We have provided a copy of D2R here in this Stuffit file in case you don't already have a copy.
••• Method:
Files on the Macintosh have a split personality: they may consist of two separate chunks of information. Applications typically have a large resource "fork" containing the code, dialogs, menus, and lots of other fascinating stuff, and no data fork. Documents usually contain a data fork with text and graphics, and have only a small resource fork or none at all. The typical HyperCard stack has a data fork in which the bitmaps, buttons, fields, scripts, and most of the functionality of the stack are stored. But stacks are unusual documents in that they may also contain a wide assortment of resources in the resource fork. There might be XCMDs, XFCNs, fonts, dialogs and their item lists, and even Desk Accessories. So to create a new stack we need to create both new forks.
Where does NewSTAK get the information to do this? To create the data fork, it assumes that you've provided a resource of type "STAK" that contains the entire data fork exactly as you wish it to appear in the new stack. During the creation of the new stack, NewSTAK simply copies this STAK resource from the resource fork of the parent stack to the data fork of the daughter stack.
To create the resource fork, NewSTAK copies every resource it finds in the parent stack over to the resource fork of the daughter stack. This includes at least the
"STAK" resource used above, and probably also the NewSTAK XCMD itself (unless that's in the Home stack.) Thus the new stack will have the ability to create new stacks of its own. The resource fork and each of its resources may be of any length, as NewSTAK will copy in bites no larger than 32K.
The careful reader will note that the new stack thus contains two copies of the original data fork, one copy in each of the new forks.
••• Creating the STAK resource:
To create a STAK resource, first create a stack exactly like you want to create later under script control. You'll probably Paste one card from each background if there's more than one background. Quit HyperCard.
Next, use the application "D2R" to Load the entire data fork of this new stack into one resource, and give it the resource type "STAK". Then tell D2R to create a new file with the resource. If you want to be able to create several types of stacks, you will need to create a STAK resource for each, giving each a unique resource ID number, and saving each in a separate file.
When you're done creating a file for each STAK, quit D2R. Now, use ResEdit to copy the STAK resource(s) from the new file(s) into the resource fork of the stack from which you wish to use NewSTAK. While you're in ResEdit, be sure to copy the NewSTAK XCMD from this demo stack to your own parent stack or Home stack.
••• Syntax:
The official syntax for the NewSTAK XCMD is
NewSTAK [newname [, STAK#]]
In other words, the XCMD may be called with up to two parameters. The first parameter ("newname") is a full path name and file name of the stack that you wish to create. If you leave it entirely blank or specify an empty string, NewSTAK will use the current folder and the current stack name prefixed with "New ". If you specify a file name but not a folder, NewSTAK will put the new stack in the same folder as the parent stack. The standard way to designate a full pathname is to start with the disk name and add each of the folder names in turn until you get down to the file name itself. You must separate each of the disk/folder/file names by colons. A typical pathname might look like "MyDisk:Hypercard Folder:my Stack".
The second parameter ("STAK#") should be the resource ID number of the STAK resource you wish to use. Thus you might want to create several STAK resources for different purposes, in order to create new stacks from each under script control. If you don't specify a STAK#, NewSTAK will use the first STAK resource it finds.
••• Possible errors:
As with any routine that uses the File Manager, there are lots of things that can go wrong. NewSTAK should be able to handle any of them gracefully.
For example, NewSTAK will refuse to create a new stack if there's already a file of any kind with the name you specify. It will also give up quite quickly if there's not enough room on the disk, or the disk is write-protected. Another possible problem can crop up if there's not enough heap space (RAM memory) to read in the STAK resource; the XCMD will return the result "STAK resource not found or unsufficient RAM.'" Since the Resource Manager reads the entire STAK resource into RAM in one piece, you should keep the data fork of your stack-to-be as small as possible, although we have successfully tested a 500K data fork with HyperCard's Finder partition set to 1500K. Since the resources are read in 32K chunks, you can safely have many and large resources in the resource fork, such as digitized sounds.
In all cases if the XCMD call is not successful, an error will be returned in HyperCard's "the result". Your script should definitely show the user "the result" if it's not empty, as we do here. Some of the error codes are more meaningful than others, but they should be enough to clue you into what is or isn't happening.
 (January 1993).iso/Files/Hyper/N-O/NewSTAK.cpt/NewSTAK/card_3005_render.png){kind=link}